PP-6: RunInputs and testing.make_clean_run - #112

PP-6 of the v0.4.0 plan (design v0.4 §6). Based on main: PP-4 (#110) and PP-5 (#111) are merged, and main was merged in (de835c5).

Commits

1. c44798c merges PP-4's latest commits into the old PP-5 tip (history from when this PR was stacked).
2. 21e44bc and 1023830 add RunInputs, testing.make_clean_run, the contract tests and contract §9.1.
3. de835c5 merges main (PP-4 and PP-5 with their review fixes). The only conflict was the error row of docs/contract.md; main's row is a superset and was kept.
4. 973c4ca (review): read_mask reads through the mask's recorded stored axes and roles; open checks every mask's fingerprint too; make_clean_run(design=True); more contract tests.
5. 41b0d73 (review): check_sources refuses a version 1 manifest (manifest_before_v040).

What it adds

• RunInputs.open(output, experiment_root=None, masks_root=None) in the new module run_inputs.py (io layer). It refuses with RunInputsError when:

  • the manifest is version 1 ("written before v0.4.0, without the axis check");
  • the SHA-256 of plane_histograms.csv or experiment_design.csv is not the manifest's;
  • any image or mask changed or is gone (fingerprint check). The message names experiment_root= or masks_root= for files that were only moved.

  It checks the fingerprint again on every read. The table is read once, when the run is opened, and kept as a snapshot.

• It gives:

  • fovs(): Fov records with the FOV key, plane_ids, axes, roles, axes_from, channel names, dtype, significant_bits, and the Z/T/C counts. They come from the manifest and the table; nothing is parsed from names.
  • pixel_sizes(fov): value, unit and source for each role.
  • read_plane(fov, z, t): a CYX array of the stored values.
  • read_image(fov): a lazy TZCYX LazyImage.
  • Both readers return canonical order. Following the owner rule in the change log, a file whose own header names X before Y (for example ZCXY) is returned Y before X. Nothing else is reordered.
  • mask_types().
  • read_mask(fov, type, z, t): uses the recorded pairing only. It reads the mask as stored, through the manifest's axes (stored, for example IYX) and roles (for example TYX), with preprocessing's reader, which runs check_labels. It refuses a mask that changed since the run, or whose header no longer gives the recorded axes or shape. A stated shared 2-D mask is returned for any plane.
  • histograms(), design() and image_type().

  A RunInputs can be pickled and used in worker processes; a test uses multiprocessing spawn.

• morphobricks_preprocessing.testing.make_clean_run(folder, *, axes, shape, mask_types, pixel_size, design, seed) writes a two-condition experiment of named-axis OME-TIFFs, with optional masks and an optional confirmed design, runs preprocessing on it, and returns a CleanRun (experiment, output, masks, result).

• check_sources now fails every image with the single error manifest_before_v040 when the manifest is version 1 (design §6: every v1 run is redone). It does not check masks; RunInputs checks them on open and on every read.

• RunInputs, RunInputsError, Fov and LazyImage are exported. docs/contract.md gets a new §9.1, and the user guide lists the new code.

Tests

• tests/test_run_inputs.py has 23 contract tests, and tests/test_check_sources.py has one new test.

• None of the RunInputs tests can pass on main, because RunInputs doesn't exist there; collection fails with an ImportError.

• Against the PR before review (de835c5), 5 of the review's new tests fail:

  • the design tests (2);
  • a mask stored otherwise than recorded;
  • a mask changed or moved before opening;
  • the v1 refusal in check_sources.

  The others pass there; they add coverage of behaviour that was already right:

  • spawned worker processes;
  • a header that names X before Y;
  • TZCYX read from a ZTCYX file;
  • a stated plain-stack mask;
  • OME-Zarr label images.

Gate (at 41b0d73)

• ruff check and ruff format --check pass, and so does tools/check.py --rules.
• The baseline only shrank: the C901 noqa count went from 2 to 1.
• Python 3.13 with zarr 3: 1415 passed, 1 skipped. The skip is the file-mode test, which can't run as root.
• Python 3.11 with zarr 2.18: 1397 passed, 19 skipped. That is the same skip plus 18 OME-NGFF 0.5 tests that need zarr 3.
• CI is green on all seven jobs.

After this PR the owner tags v0.4.0rc1 (design §8).

https://claude.ai/code/session_01WX6rdMV1r5jUPUR94kxV5a

Generated by Claude Code